Skip to main content

Subaccount Management

A Subaccount is a way to manage your clients by separating your main account (Avenia API Main Account or BA) from others.

subAccount fluxogram

info

The diagram shows that multiple accesses can manage subaccounts related to the main account.

Create Subaccount​

When creating a Subaccount, you gain the ability to perform operations such as: KYC, OPERATIONS, BENEFICIARY BANK ACCOUNT, BENEFICIARY WALLETS, and other Avenia API features.

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/sub-accounts

Fields​

FieldTypeDescription
accountTypestringType related to this subaccount (INDIVIDUAL)
namestringName to facilitate identification of this sub-account up to 64 characters
allowedAccessIdsarray of stringOptional. Accesses of your account that see only their allowed subaccounts and get this one too, such as the advisor in charge of the customer. At most 20. Any access that can create subaccounts may send it, and List Restricted Accesses returns the candidates. An access that is not from your account is refused with allowedAccessIds is invalid.

Request body​

JSON
{
"accountType": "INDIVIDUAL",
"name": "jane doe"
}

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts" \
-H "Content-Type: application/json" \
-d '{
"accountType": "INDIVIDUAL",
"name": "jane doe"
}'

Without allowedAccessIds, a new subaccount stays hidden from every access limited to its allowed subaccounts, except the one that created it. An access in the list that sees every subaccount already sees the new one, and nothing changes for it.

Response​

The response will include the ID linked to the created Subaccount.

JSON
{
"id": "c852df87-ac61-4259-8242-6451658dfedb"
}
Sub-Account Lifecycle

Sub-accounts are permanent once created — deletion is not supported. DELETE /v2/account/sub-accounts/{id} returns 405 Method Not Allowed.

List All Subaccounts​

To view all your Subaccounts, use the list endpoint with these parameters:

Fields​

FieldTypeDescription
namestringSearch for names containing specific characters
cursorstringPagination cursor to advance through results

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/sub-accounts

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts"

Response​

JSON
{
"cursor": "MTEwLTE3NDMwMjkzNTUyODE=",
"subAccount": [
{
"subAccountId": "2eea0102-dabe-4ab6-8707-0817aa52dfe4",
"mainAccountId": "3657c184-854c-4a71-98b0-9fc8e2960ba8",
"createdAt": "2025-03-27T09:59:59.099865Z",
"accountInfo": {
"id": "87b3ab56-463c-4207-ae31-4d2bd26dc66a",
"accountType": "INDIVIDUAL",
"name": "Ada Doe"
}
}
// ... other subaccounts
]
}

Find Subaccounts by Name​

Turns subaccount names, such as a column of a spreadsheet, into subaccount IDs. A name matches regardless of case, accents and extra spaces, so jose doe finds José Doe.

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/sub-accounts/resolve-names

Fields​

FieldTypeDescription
namesarray of stringThe names to look up, from 1 to 1000.

Request body​

JSON
{
"names": ["Ada Doe", "jose doe", "Jane Roe"]
}

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts/resolve-names" \
-H "Content-Type: application/json" \
-d '{
"names": ["Ada Doe", "jose doe", "Jane Roe"]
}'

Response​

results has one entry per name sent, in the same order, repeated names included. subAccounts holds the subaccounts with that name, newest first: none when the name is not found, more than one when subaccounts share it.

JSON
{
"results": [
{
"name": "Ada Doe",
"subAccounts": [
{ "id": "2eea0102-dabe-4ab6-8707-0817aa52dfe4", "name": "Ada Doe" }
]
},
{
"name": "jose doe",
"subAccounts": [
{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "José Doe" },
{ "id": "16fd2706-8baf-433b-82eb-8c7fada847da", "name": "Jose Doe" }
]
},
{
"name": "Jane Roe",
"subAccounts": []
}
]
}

Only the subaccounts that List All Subaccounts returns to your access are searched, so a subaccount your access does not see is not found. The request only reads: a view-only access can make it. With a login (JWT), it still needs TOTP on the access, as every POST does — see When TOTP is required. Sending no names or more than 1000 returns 400 names is invalid, with extraInfo send from 1 to 1000 names.

Get Specific Subaccount​

Retrieve details of a specific Subaccount using its ID.

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/sub-accounts/SUBACCOUNT-ID-HERE

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts/SUBACCOUNT-ID-HERE"

Response​

JSON
{
"subAccountId": "2eea0102-dabe-4ab6-8707-0817aa52dfe4",
"mainAccountId": "3657c184-854c-4a71-98b0-9fc8e2960ba8",
"createdAt": "2025-03-27T09:59:59.099865Z",
"accountInfo": {
"id": "87b3ab56-463c-4207-ae31-4d2bd26dc66a",
"accountType": "INDIVIDUAL",
"name": "Ada Doe"
}
}

Conclusion​

You can now fully utilize Subaccount capabilities. Remember to include the subAccountId parameter in endpoints that allow Subaccount operations.